classdef dotsTransaction
    % @class dotsTransaction
    % Portable representation of property access or method call.
    % @details
    % Holds enough information to specify an interaction between
    % dotsAllRemoteObjectManagers objects.  Interactions include creation
    % and removal of managed objects and managed object or manager method
    % calls and property access.
    % @details
    % dotsTransaction does not define many methods.  Its main function is
    % to define (and document) properties that represent object
    % interactions, and to produce structs with equivalent fields.
    %
    % @ingroup foundation
    
    properties
        % string unique identifier for this transaction object
        UID = '';
        
        % string UID for a managed object
        objectUID = {};

        % string name of a object manager's method
        methodName = '';

        % cell array of arguments to pass to the named method
        methodArgs = {};

        % true or false, whether the named method returns an output
        hasOutput = false;
        
        % property value or method return value
        returnValue = [];

        % object property to get or set or take the output of a method
        propertyName = '';
        
        % time when the transaction was initiated, from the client
        % manager's clockFunction
        startTime = [];
        
        % time it took for the client manager to receive an acknowledgement
        % from the server (if necessary), from the client
        % manager's clockFunction
        acknowledgeTime = [];
        
        % time when the transaction was all done, from the client
        % manager's clockFunction
        finishTime = [];
        
        % time just before the transaction was carried out, from the server
        % manager's clockFunction
        actionStartTime = [];
        
        % time just after the transaction was carried out, from the server
        % manager's clockFunction
        actionFinishTime = [];
    end
    
    methods (Access = private)
        % Constructor is private.
        % @details
        % Use dotsTransaction.newTransactionStruct() to get a struct
        % equvalent to a dotsTransaction object.
        function txn = dotsTransaction
        end
        
        % Convert a dotsTransaction object to an equivalent struct.
        function s = toStruct(txn)
            warning('off', 'MATLAB:structOnObject');
            s = struct(txn);
        end
    end
    
    methods (Static)
        % Create a new struct with fields that match the properties of the
        % dotsTransaction class.
        % @param varargin optional property-value pairs to assign to the
        % new struct.
        % @details
        % Use this method instead of the dotsTransaction constructor.
        % @details
        % Returns a struct with fields and default values that match those
        % of the dotsTransaction class.  @a varargin may contain pairs of
        % property names and values to be assigned to the new struct.
        function txn = newTransactionStruct(varargin)
            txnObj = dotsTransaction;
            for ii = 1:2:length(varargin)
                txnObj.(varargin{ii}) = varargin{ii+1};
            end
            txn = txnObj.toStruct;
        end
    end
end